SDK Web

Ajoutez AR Clip VPS à votre propre page web. Le SDK Web trouve, directement dans le navigateur, où se trouve le visiteur sur vos cartes VPS, sans aucune application à installer.

Avant de commencer

Une clé d'API. Pour en obtenir une, écrivez-nous via le Support.
Les identifiants de lieu de vos cartes. Chaque carte en a un : voir l'Introduction.
Une page servie en HTTPS. Les navigateurs ne donnent accès à la caméra et aux capteurs de mouvement qu'aux pages sécurisées. localhost compte comme sécurisé.

Installation

npm install @web-ar-studio/webar-engine-sdk

Le package est sur npm et inclut ses types TypeScript.

Lancer le VPS

Le VPS tourne dans une session de suivi du monde. Ajoutez vps à init() et indiquez-y vos identifiants de lieu. Le SDK ne dessine rien lui-même : affichez la scène avec le moteur de votre choix, que ce soit three.js, Babylon.js, PlayCanvas ou du WebGL pur.

import * as THREE from "three";
import WAS, {
  PROJECT_MODE_SLAM,
  TRIGGER_MODE_SLAM,
  CAMERA_MODE_ENVIRONMENT,
  PROVIDER_8THWALL,
  EVENT_FRAME,
  EVENT_VPS_READY,
  EVENT_VPS_LOCALIZED,
  EVENT_VPS_NOT_LOCALIZED,
  EVENT_VPS_ERROR,
} from "@web-ar-studio/webar-engine-sdk";

const was = new WAS();

const { canvas, context } = await was.init({
  apiKey: "your-api-key",
  mode: PROJECT_MODE_SLAM,
  cameraMode: CAMERA_MODE_ENVIRONMENT,
  container: document.querySelector("#ar"),
  triggers: [{ id: 1, mode: TRIGGER_MODE_SLAM, source: null }],
  vps: { locationIds: ["your-location-id"] },
});

const renderer = new THREE.WebGLRenderer({ canvas, context });

was.on(EVENT_VPS_READY, () => console.log("VPS started"));
was.on(EVENT_VPS_LOCALIZED, ({ locationId, offset }) => {
  console.log("Found the place on map", locationId, offset);
});
was.on(EVENT_VPS_NOT_LOCALIZED, ({ status, statusDescription }) => {
  console.log("Not found yet:", status, statusDescription);
});
was.on(EVENT_VPS_ERROR, (message) => console.warn("VPS error:", message));

// Le suivi et le VPS démarrent avec le callback d'image. Enregistrez-le sur un appui :
// WebXR et les capteurs de mouvement de l'iPhone exigent un geste de l'utilisateur.
startButton.onclick = () =>
  was.on(EVENT_FRAME, () => renderer.render(scene, camera));

Sans locationIds, le VPS localise de façon globale, sans viser une carte précise. C'est plus long : augmentez requestTimeoutMs.

Passez vps à init()

Dans Chrome sur Android, l'accès à la caméra pour le VPS n'est accordé qu'au démarrage de la session. Si vous démarrez sans vps, vous ne pourrez plus activer le VPS dans cette session : setupVPS() lève VpsError.

Où ça fonctionne

Le SDK choisit un moteur de suivi (provider) sur l'appareil. Avec la valeur par défaut "auto", il essaie d'abord webxr, puis 8thwall.

Moteur	Où	VPS
`webxr`	Chrome sur Android	Oui. Le SDK place lui-même la scène sur la carte.
`8thwall`	Navigateurs sans WebXR, comme Safari sur iPhone	Oui. Vous appliquez `offset` vous-même.
`arclip-webar`	Seulement si vous le choisissez	Non

Placer le contenu sur la carte

Placez votre contenu dans les coordonnées de votre carte VPS. Quand le VPS trouve le lieu, EVENT_VPS_LOCALIZED fournit offset : le déplacement qui fait passer le monde du suivi sur la carte.

Sur webxr, le SDK a déjà appliqué offset, en douceur : le contenu de la carte apparaît à sa place.
Sur 8thwall, le SDK se contente de transmettre offset. Regroupez le contenu de la carte dans un groupe et donnez-lui l'inverse de offset à chaque localisation :

const mapRoot = new THREE.Group(); // tout ce qui est placé en coordonnées de carte
scene.add(mapRoot);

was.on(EVENT_VPS_LOCALIZED, ({ offset }) => {
  if (was.getActiveProviderId() !== PROVIDER_8THWALL) return; // webxr l'applique lui-même
  const { position: p, orientation: q } = offset;
  new THREE.Matrix4()
    .compose(
      new THREE.Vector3(p.x, p.y, p.z),
      new THREE.Quaternion(q.x, q.y, q.z, q.w),
      new THREE.Vector3(1, 1, 1),
    )
    .invert()
    .decompose(mapRoot.position, mapRoot.quaternion, mapRoot.scale);
});

Le SDK n'accepte un résultat que si la correspondance est assez fiable et si le saut depuis le résultat précédent est faisable à pied. Tout le reste arrive comme EVENT_VPS_NOT_LOCALIZED. Ainsi, le contenu ne saute pas dans les lieux qui se ressemblent, comme les longs couloirs.

Événements

Événement	Ce que vous recevez
`EVENT_VPS_READY`	Rien. Le VPS a démarré.
`EVENT_VPS_LOCALIZED`	`locationId`, `offset` (`position`, `orientation`), `trackingPosition`, `trackingRotation`, `vpsPosition`, `vpsRotation`, `timestamp`
`EVENT_VPS_NOT_LOCALIZED`	`status`, `statusDescription`, `failCount`
`EVENT_VPS_ERROR`	Un message d'erreur, sous forme de chaîne

Piloter le VPS

Méthode	Ce qu'elle fait
`startVPS()`, `stopVPS()`	Reprend ou met en pause la localisation
`isVPSActive()`	Indique si le VPS tourne
`setVPSLocationIds(ids)`	Passe à d'autres cartes ; une liste vide localise de façon globale
`setupVPS(config)`	Change les réglages du VPS pendant une session
`updateVPSSession()`	Démarre une nouvelle session VPS : les résultats précédents n'influencent plus les nouveaux
`resetTracking()`	Annule la correction VPS et repart de zéro, par exemple après un mauvais résultat

Réglages

Tous les champs de vps sont facultatifs. Le SDK reprend apiKey depuis init(), inutile de le répéter.

Champ	Par défaut	Ce qu'il fait
`locationIds`	aucun	Les cartes comparées à l'image de la caméra. Sans lui, le VPS localise de façon globale.
`captureInterval`	`2500`	Délai entre deux requêtes de localisation, en ms
`requestTimeoutMs`	`20000`	Durée d'attente d'une réponse, en ms
`maxFailsCount`	`5`	Nombre d'échecs d'affilée avant que le SDK démarre une nouvelle session VPS
`imageFormat`	`"jpeg"`	`"jpeg"` ou `"webp"`. N'utilisez WebP qu'avec un serveur qui sait le lire. Si le navigateur ne sait pas encoder le WebP, le SDK envoie du JPEG.
`jpegQuality`	`1`	Qualité de l'image, de 0 à 1
`targetWidth`, `targetHeight`	`540`, `960`	Taille de l'image envoyée au serveur
`minInlierRatio`, `minNumInliers`	`0.6`, `600`	Le niveau de fiabilité qu'une correspondance doit atteindre pour être retenue
`maxJumpBaseMeters`, `maxJumpSpeedMps`	`3`, `2`	Jusqu'où un nouveau résultat peut s'éloigner du précédent : `maxJumpBaseMeters` plus `maxJumpSpeedMps` par seconde écoulée depuis le dernier résultat
`serverUrl`	AR Clip VPS	Un autre serveur VPS
`sendApiKeyHeader`	`true`	Envoie la clé dans l'en-tête `x-vps-apikey`. Ne le désactivez que pour votre propre serveur, s'il n'accepte pas cet en-tête.

Erreurs

Si le VPS ne peut pas tourner dans cette session, init() ou une méthode VPS échoue avec une erreur nommée VpsError (constante VPS_ERROR). Les erreurs après le démarrage, comme une requête qui échoue, arrivent dans EVENT_VPS_ERROR.

Pour aller plus loin

Le README du package décrit les autres modes de suivi, les ancres et la configuration complète avec three.js.
Pour mettre en place le VPS sans code, utilisez les Scènes VPS dans AR Clip Studio.

Suite : Appareils compatibles — téléphones, navigateurs et casques.

Avant de commencer​

Installation​

Lancer le VPS​

Où ça fonctionne​

Placer le contenu sur la carte​

Événements​

Piloter le VPS​

Réglages​

Erreurs​

Pour aller plus loin​